<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>The root window</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="PyCairo, graphics, Python, 2D vector library, 
root window, desktop window">
<meta name="description" content="In this chapter of the PyCairo tutorial, we will
have examples that work with the root window.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>Root window</h1>


<p>
In this part of the PyCairo tutorial, we will work with the root window. 
The root window is the desktop window where we usually have icon shortcuts.
</p>

<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<p>
It is possible to manipulate with the root window. From the programmer's perspective,
it is just a special kind of a window. 
</p>


<h2>Transparent window</h2>

<p>
Our first example will create a transparent window. We will see, what it beneath
of the window object. 
</p>

<pre class="code">
#!/usr/bin/python

'''
ZetCode PyCairo tutorial 

This code example shows how to
create a transparent window.

author: Jan Bodnar
website: zetcode.com 
last edited: August 2012
'''

from gi.repository import Gtk
import cairo


class Example(Gtk.Window):

    def __init__(self):
        super(Example, self).__init__()
        
        self.tran_setup()
        self.init_ui()
        
        
    def init_ui(self):    

        self.connect("draw", self.on_draw)        

        self.set_title("Transparent window")
        self.resize(300, 250)
        self.set_position(Gtk.WindowPosition.CENTER)
        self.connect("delete-event", Gtk.main_quit)
        self.show_all()
        
        
    def tran_setup(self):    
        
        self.set_app_paintable(True)  
        screen = self.get_screen()
        
        visual = screen.get_rgba_visual()       
        if visual != None and screen.is_composited():
            self.set_visual(visual)              
        
    
    def on_draw(self, wid, cr):

        cr.set_source_rgba(0.2, 0.2, 0.2, 0.4)
        cr.set_operator(cairo.OPERATOR_SOURCE)
        cr.paint()
       
    
def main():
    
    app = Example()
    Gtk.main()
        
        
if __name__ == "__main__":    
    main()
</pre>

<p>
To create a transparent window, we get the visual of the screen object
and set it for our window. In the on_draw() method, we draw over the
screen's visual object. This createas an illusion of partial transparency.
</p>

<pre class="explanation">
self.set_app_paintable(True)  
</pre>

<p>
We must set the application to be painted on.
</p>

<pre class="explanation">
screen = self.get_screen()
</pre>

<p>
The <code>get_screen()</code> method returns the screen object.
</p>

<pre class="explanation">
visual = screen.get_rgba_visual()
</pre>

<p>
From the screen window, we get its visual. The visual contains the low level
display information.
</p>

<pre class="explanation">
if visual != None and screen.is_composited():
    self.set_visual(visual) 
</pre>

<p>
Not all displays support this operation. Therefore, we check if
our screen supports composition and the returned visual is not 
None. We set the screen's visual to be the visual of our window.
</p>

<pre class="explanation">
def on_draw(self, wid, cr):

    cr.set_source_rgba(0.2, 0.2, 0.2, 0.4)
    cr.set_operator(cairo.OPERATOR_SOURCE)
    cr.paint()
</pre>

<p>
We use a partially transparent source to draw over the screen
window. The <code>cairo.OPERATOR_SOURCE</code> creates a composition
operation where we draw over the source. Which is the screen window.
To get full transparency, we set the alpha value to 0 or use the
<code>cairo.OPERATOR_CLEAR</code> operator.
</p>

<img src="/img/gfx/pycairo/trwindow.png" alt="Transparent window">
<div class="figure">Figure: Transparent window</div>


<h2>Taking a screenshot</h2>

<p>
The root window is also essential in taking a screenshot.
</p>

<pre class="code">
#!/usr/bin/python

'''
ZetCode PyCairo tutorial 

This code example takes a screenshot.

author: Jan Bodnar
website: zetcode.com 
last edited: August 2012
'''

from gi.repository import Gdk
import cairo


def main():
    
    root_win = Gdk.get_default_root_window()

    width = root_win.get_width()
    height = root_win.get_height()    
    
    ims = cairo.ImageSurface(cairo.FORMAT_ARGB32, width, height)                
    pb = Gdk.pixbuf_get_from_window(root_win, 0, 0, width, height)
        
    cr = cairo.Context(ims)    
    Gdk.cairo_set_source_pixbuf(cr, pb, 0, 0)     
    cr.paint()

    ims.write_to_png("screenshot.png")
        
        
if __name__ == "__main__":    
    main()
</pre>

<p>
The example captures a snapshot of the entire screen. 
</p>

<pre class="explanation">
root_win = Gdk.get_default_root_window()
</pre>

<p>
We get the root window with the <code>Gdk.get_default_root_window()</code>
method call.
</p>

<pre class="explanation">
width = root_win.get_width()
height = root_win.get_height() 
</pre>

<p>
We determine the width and the height of the root window.
</p>

<pre class="explanation">
ims = cairo.ImageSurface(cairo.FORMAT_ARGB32, width, height)
</pre>

<p>
An empty image surface is created. It has the size of the root 
window.
</p>

<pre class="explanation">
pb = Gdk.pixbuf_get_from_window(root_win, 0, 0, width, height)
</pre>

<p>
We get a pixbuf from the root window using the <code>Gdk.pixbuf_get_from_window()</code>
method call. A pixbuf is an object that describes an image in memory. It
is used by the GTK library.
</p>

<pre class="explanation">
cr = cairo.Context(ims)    
Gdk.cairo_set_source_pixbuf(cr, pb, 0, 0)     
cr.paint()
</pre>

<p>
In the above code lines, we create a Cairo drawing context on the
image surface that we have created earlier. We place the pixbuf
on the drawing context and paint it on the surface. 
</p>

<pre class="explanation">
ims.write_to_png("screenshot.png")
</pre>

<p>
The image surface is written to a PNG image using the
<code>write_to_png()</code> method.
</p>


<h2>Showing message</h2>

<p>
In the third example, we will show a message on the desktop window.
</p>

<pre class="code">
#!/usr/bin/python

'''
ZetCode PyCairo tutorial 

This code example shows a message on the desktop
window.

author: Jan Bodnar
website: zetcode.com 
last edited: August 2012
'''


from gi.repository import Gtk, Gdk, Pango
import cairo


class Example(Gtk.Window):

    def __init__(self):
        super(Example, self).__init__()
        
        self.setup()       
        self.init_ui()

        
    def setup(self):    
        
        self.set_app_paintable(True)   
        self.set_type_hint(Gdk.WindowTypeHint.DOCK)
        self.set_keep_below(True)
        
        screen = self.get_screen()
        visual = screen.get_rgba_visual()       
        if visual != None and screen.is_composited():
            self.set_visual(visual)          
        
        
    def init_ui(self):    

        self.connect("draw", self.on_draw)        
        
        lbl = Gtk.Label()
        text = "ZetCode, tutorials for programmers."
        lbl.set_text(text)        
        
        fd = Pango.FontDescription("Serif 20")
        lbl.modify_font(fd)                
        lbl.modify_fg(Gtk.StateFlags.NORMAL,Gdk.color_parse("white"))        
        
        self.add(lbl)

        self.resize(300, 250)
        self.set_position(Gtk.WindowPosition.CENTER)
        self.connect("delete-event", Gtk.main_quit)
        self.show_all()
                                      
    
    def on_draw(self, wid, cr):
        
        cr.set_operator(cairo.OPERATOR_CLEAR)
        cr.paint()
        cr.set_operator(cairo.OPERATOR_OVER)
        
    
def main():
        
        app = Example()
        Gtk.main()        

        
if __name__ == "__main__":    
    import signal
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    main()
</pre>

<p>
The code displays a message label on the root window. 
</p>

<pre class="explanation">
self.set_app_paintable(True) 
</pre>

<p>
We will be manipulating the application window, so we make it paintable.
</p>

<pre class="explanation">
self.set_type_hint(Gdk.WindowTypeHint.DOCK)
</pre>

<p>
Implementing this window hint removes window borders and
decoration.
</p>

<pre class="explanation">
self.set_keep_below(True) 
</pre>

<p>
We keep the application always at the bottom, just over the root window.
</p>

<pre class="explanation">
screen = self.get_screen()
visual = screen.get_rgba_visual()       
if visual != None and screen.is_composited():
    self.set_visual(visual)  
</pre>

<p>
We set the visual of the screen to be the visual of our application.
</p>

<pre class="explanation">
lbl = Gtk.Label()
text = "ZetCode, tutorials for programmers."
lbl.set_text(text)    
</pre>

<p>
We put a message label on the application window.
</p>

<pre class="explanation">
fd = Pango.FontDescription("Serif 20")
lbl.modify_font(fd)                
lbl.modify_fg(Gtk.StateFlags.NORMAL,Gdk.color_parse("white"))   
</pre>

<p>
With the help of the Pango module, we change the appearance of
the text.
</p>

<pre class="explanation">
def on_draw(self, wid, cr):
    
    cr.set_operator(cairo.OPERATOR_CLEAR)
    cr.paint()
    cr.set_operator(cairo.OPERATOR_OVER)
</pre>

<p>
We use the <code>cairo.OPERATOR_CLEAR</code> operator to clear
the background of the window. Then we set the <code>cairo.OPERATOR_CLEAR</code>
to let the label widget be drawn. 
</p>

<pre class="explanation">
if __name__ == "__main__":    
    import signal
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    main()
</pre>

<p>
There is an older <a href="https://bugzilla.gnome.org/show_bug.cgi?id=622084">bug</a>
that does not allow us to terminate the application launched from the terminal 
with the Ctrl+C shortcut. Adding the two lines is a workaround for this.
</p>

<img src="/img/gfx/pycairo/desktopwrite.png" alt="Message on the root window">
<div class="figure">Figure: Message on the root window</div>


<p>
In this chapter we have worked with the desktop window in PyCairo.
</p>

<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div> 
<br>


<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified August 30, 2012 <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>

